Proxy (instrumental) SVAR Modeling
===================================

A ``proxy_svar_model`` object is a structural VAR identified
with **external instruments** ("proxies"): observed series that
are correlated with a structural shock of interest but with no
other shock. It extends the structural VAR object, so data
handling, estimation, forecasting and the various decompositions
are exactly as described in :doc:`Main Structural VAR Modeling` and
:doc:`Main Reduced form VAR Modeling`; this page covers what is specific to
the proxy case.

.. contents::
   :local:
   :depth: 2


The model
----------

The structural VAR is as usual,

.. math::

    A_{0}(r_{t}) y_{t} = C(r_{t}) x_{t}
                       + A_{1}(r_{t}) y_{t-1} + \cdots
                       + A_{p}(r_{t}) y_{t-p}
                       + \varepsilon_{t},

and each proxy :math:`m_{t}` is linked to one structural shock
by

.. math::

    m_{t} = \beta_{m}(r_{t}) \varepsilon_{y,t}
          + \sigma_{m}(r_{t}) \varepsilon_{m,t},

with :math:`r_{t} = 1, 2, \dots, h` and transition probabilities
:math:`p_{r_{t}, r_{t+1}}(I_{t})`. Here :math:`\varepsilon_{y,t}`
is the structural shock the proxy instruments,
:math:`\varepsilon_{m,t}` is proxy measurement noise,
:math:`\beta_{m}` the relevance coefficient, and
:math:`\sigma_{m}` the noise scale. The proxy series themselves
are part of the time-series database passed to ``estimate``.


Creating a proxy SVAR
----------------------

The proxy structure is the first argument; the rest of the
signature is the SVAR one::

    mdl = proxy_svar_model(proxies, varlist, ...
        lag_length         = nlags, ...
        constant_term      = const, ...
        deterministic_vars = exog, ...
        markov_chains      = mc);

``proxies`` is an array of structs, one per instrument, with
fields:

* ``var`` -- name of the endogenous variable whose shock the
  proxy instruments.
* ``eqtn`` -- the proxy-equation number (matching the
  declaration order of ``var``).
* ``coef`` -- the name of the proxy relevance coefficient
  (:math:`\beta_{m}` above).
* ``shock_eqtn`` -- the equation whose structural shock is
  related to the proxy.

For example, to instrument the monetary-policy shock (the shock
in the ``R`` equation) with a high-frequency surprise series
``mp_surprise``::

    prox            = struct();
    prox.var        = 'R';
    prox.eqtn       = 1;
    prox.coef       = 'beta_mp';
    prox.shock_eqtn = 'R';

    endog = {'R','PAI','GROWTH'};

    mdl = proxy_svar_model(prox, endog, ...
        lag_length    = 4, ...
        constant_term = true);

(``varlist`` must be ordered consistently with the proxy
specification.)


Estimation, IRFs, decompositions, forecasting
----------------------------------------------

These are called exactly as for an SVAR -- ``estimate`` (with an
optional prior and any additional identifying restrictions on
``a0`` / ``a1`` / ...), ``print_structural_form``, ``irf``,
``variance_decomposition``, ``historical_decomposition``,
``forecast``, ``bootstrap``. The proxy relevance and noise
parameters (``beta_*``, ``sigma_*``) are estimated alongside the
VAR coefficients, and the proxy equations supply the
identification of the instrumented shock(s). See
:doc:`Main Structural VAR Modeling` and :doc:`Main Reduced form VAR Modeling` for the call
patterns and the plotting helpers.


Adding regime switching
------------------------

A Markov-chain structure can be passed in ``markov_chains`` as
for the SVAR; the proxy relevance and noise (:math:`\beta_{m}`,
:math:`\sigma_{m}`) and/or the VAR coefficients can be made
regime-dependent through ``controlled_parameters``, and
time-varying transition probabilities are specified exactly as
in :doc:`Main Reduced form VAR Modeling`.